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Foreword 

Thi: Fudcral Infnrniatiun I'rocessinj: Staiulanls rublication Series of the National 
Bureau of Staiulards is the oHicial pul>lication ri'latirijr to .standards adopted and 
promuliratcd under the provisions of Public Law SO-liOd (Brooks Bill) and un^^'M* Fart 
r. of Title 15, Codf of Federal Rejrulations. These lejrislative and executive mandates 
have driven the Secretary of Commeree important responsibilities for improving: the 
utilization and nianajrement of computers and automatic data processin^^ syytenis in 
thf Federal Clovernment. To carry out the Secretary's responsibilities, the NBS, through 
its Institute for Computer Sciences and Technolojry, provides leadership, technical 
jriiidance, and coordination of jrovei-nment efforts in the development of technical 
jruidelines and standards in these areas. 

In Octoi'rr 11»T4, the Comptroller Cleneral of the United States in a report to the 
Conjrress noted that "adequate dtjcumuntation of computer proiLcranis is clearly an 
es.sential element of etlicient and economical use of computer systems." Good documen- 
tation should provide information to support the etft-ctive nianatrement of A DP re- 
sources and to facilitate tlie interchanjre of infoi niation. The NBS is pleaded to make, 
these (Juidelines for Documentation of Computer Pro;:ranis and Automated Data 
Systems available for use by >\*deral a^rencie.s in establishittjr and evaluatinj^ docu- 
mentation practices. 

■ RUTH M. DAVIS, Director 

Institute for Computer Sciences 
and Technolojry 

Abstract 

These jruidolines provide a basis for determininjr the content and extent of docu- 
mentation for computer pro:* rams .la^l automated data systems. Software development 
phase.< and related document types are identified, several examples of documentation 
options are ^MVen, and content ^ruidelines for ten document types are provided. The 
ten document types are* 

Functional Requirements Document 

Data Requirements Document 

System/Subsystem Specification 

Program Specification 

Data Base Specification 

Users Manual 

Operations Manual 

Proprram Maintenance Manual 

Test Plan 

Test Analysis Report 

The guidelines are intended to be a basic reference and a checklist for general use 
throughout the Federal Government to plan and evaluate documentation practices. 

Key words: Automated data systems: computer programs; documentation; documen- 
tation content guidelines; FIPS guidelines; software. 
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Federal Information Processing: Publications are issued by the National Bureau of Standards pursuant to the 
Federal Property and Administrative Services Act of 1940 as amencied, Public Law 89-306 (79 Stat 1127), and as 
implemented by Executive Order 11717 (38 FR 12315, dated May 11, 1973), and Part 0 of Title 15 CFR (Code of 
Federal Reprulations). 

Name of Guideline. Guidelines for Docunientation of Computer Programs and Automated Data 
Systems. 

Category of Guideline. Federal General Applications and Data Standard— Softwai'e, Documenta- 
tion. 

Explanation. These guidelines provide a basis for determining the content and extent of docu- 
mentation for computer programs and automated data systems. 

Approving Authority. Department of Commerce, National Bureau of Standai-ds (Institute for 
Computer Sciences and Technology). 

Maintenance Agency. Department of Commerce, National Bureau of Standards (Institute for 
(Computer Sciences and Technology). 

Applicability. Tiieso guidelines are intended to be a I)asic reference and a checklist for general 
use throughout the Federal Government to plan and evaluate documentation practices. 

Implementation Schedule. Implementation is desirable at the earliest possible date to achieve more 
effective use of ADP resources and to facilitate interchange of information about computer pro- 
grams and automated data systems. 

Where documentation standards are already in existence, it is recommended that they be re- 
viewed for conformance with the intent of this guideline and revi.sed as needed to be consistent 
with the best use of available resources. 

Specifications. The following pages define software development phases and related document 
types, give several examples of documentation options, and provide content guidehnes for ten 
document types. 



a. Automated Data System Documentation Standards Manual, Department of Defense Man- 
ual 4120.17-M, December 1972. 

b. Computer Program Documentation Guideline, National Aeronautics and Space Administra- 
tion, NHB-2411.1, July 1971. 

c. Software Summary for Describing Computer Programs and Automated Data Systems, 
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Federal Inforniaiion Processing Standards Publication 30, U.S. Department of Coninierce, June 
30, 197^1. 

Definitions. 

a. Computer program. A series of instructions or statements, in a form acceptable to a com- 
puter, prepared in order to achieve a certain result. 

1). Automated data system. A set of logically related computer programs designed to accom- 
plish specific objectives or functions. 

Where To Obtain Copies of the Guideline. 

a. Federal Government activities should obtain copies of this publication from the estab- 
lished sources within each agency. When there is no established source, purchase orders should 
he submitted to the National Bureau of Standards. Institute for Computer Sciences and Tech- 
nology. Office of ADP Standards Management, Technology Building, Washington, D.C. 20234. 
Refer to the Federal Information Processing Standard Number 38. 

b. Others may obtain copies of the FIPS PUB from the Superintendent of Documents, U.S. 
Government Printing Office, Washington, D.C. 20402 (SD Catalog Number C13.52:38). There 
is a 25 percent discount on quantities of 100 or more. When ordering, specify document number, 
title, and SD Catalog Number. Payment may be made by check, money order, coupons, or de- 
posit account. 

c. Copies of this FIPS PUB are also available in Microfiche from the National Technical 
Infomnation Service, 5285 Port Royal Road, Springfield, Virginia 22161 at 95 cents a copy. Re- 
fer to Report Number NBS-FIPS-PUB-38. 
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Introduction 

The planning", design, development, and implementation of computer programs and 
automated data systciiis ' represent a considerable investment of human and automated 
resources. To maximize the return on this investment, and to provide for cost-effective 
operation, revision, and maintenance, sufficient documentation is needed at each stage 
of the software devel.)pment life cycle. This publication has been pi'epared in response 
to that need- 
Documentation provides information to support the effective management of ADP 
resources and to facilitate the interchange of information. It serves to: 

— Provide managers with technical documents to review at the significant develop- 
ment milestones, to determine that requirements have been met and that resources 
should continue to be expended. 

— Record technical information to allow coordination of later development and use/ 
modification of the software. 

— Facilitate understanding among managers, developers, programmers, operators, 
and users by providing information about maintenance, training, changes, and 
operation of the software. 

— Inform other potential users of the functions and capabilities of the software, so 
that they can determine whether it will serve their needs. 

The quality and consistency of software documentation depend on management com- 
mitment and the technical environment. The criteria for evaluating the adequacy of 
documentation will vary directly with the perceived need for documentation. The utility, 
quality, and acceptability of the documents prepared will provide a measure of the man- 
::gement judgment exercised in implementin^jc the documentation guidelines. 

This publication provides guidelines for the content of software documentation and 
examples of how management might determine wheil and how to utilize the ten docu- 
ment types described. Part 1 states the purpose of each document type and its relation- 
ship to the software life cycle. Part 2 discusses considerations in using these document- 
ation guidelines including examples of agency or organization level guidance criteria 
that can be applied to determine the extent of documentation required- Part 3 presents 
the content guidelines for the ten document types.^ 



• Thr«niKhout this FIPS PUR 38 "software" i.-* ustnl Ux lieu of 'Vomputcr projrrnm nml/or Juitonmtc<i ilntn system. *' 
- N«tt? th;it the Software Summary for Dwcribin); Computt-r Pro^rrams arnl Automated Dntn Systems (FIPS PUIJ 30 > is 
f<>f<siii«>rc({ n coniimncnt of florum(*ntation. in this context. 



5 

8 



FIPS 1*1! H 38 



PART 1. DOCUMENTATION WITHIN THE SOFTWARE LIFE CYCLE 

1 1 Scope. Computer programs and automated data systems evolve in phases from the time 
that an idea to create the softw^ire occurs through tlie time that tiiat software produces the re- 
quired output. It is recognized that there are in current usage maijy different terminologies to 
identify these phases and the stages within these phases. Three phases applicable to the software 
life cycle are: initiation, development, and operation. The development phase is further sub- 
divided into four stages. 

This publication provides content guidelines for ten document types generally prepared 
during the development pha.se. Figure 1 relates the preparation of the ten documen. types to 
the stages in the development pfetse. The amount of documentation produced is flexible, and this 
flexibility is discussed in Part 2.. Content guidelines for the ten ^^Pes >s Provi^^^^^^^^ 

Part 3. Each of these document types can stand alone or be combined with otheis to meet .spe- 
cific documentation requirements. 



Fir.T'RE 1. nociimnitntion witkht the software life cycle 



INITIATION 
PHASE 





DEVi;:LOPMENT PHASE 




OPERATION 
PHASE 


Definition 
Stage 


Design 
Stage 


Programming 
Stage 


Test 
Stage 




Functional 
Requirements 
Document 


System/ 
Subsystem 
Specification 

Program 
Specification 


Users 
Manual 

Operations 
Manual 






Data 
Requjrenu»nts 
Document 


Data Base 
Specification 


Program 
Maintenance 
Manual 








Test Plan 


Test Analysis 
Report 





1 2. Phjuses. While the terminology used to describe the phases is arbitrary it provides a con- 
venient framework within which the development of software may be discussed. 

1.2.1. Initiation. During the Initiation Phase, the objectives and general definition of the 
reciuirements for the software are established. Feasibility studies cost-benefit analyses and 
the documentation prepared within this phase are determined by agency procedures and 
practices. 

1.2.2. Development. During the Development Phase, the requirements for the software 
are determined and the software is then defined, specified programmed, and tested Docu- 
mentation is prei>ared within this phase to provide an adequate record of the technical in- 
formation developed. 

1.2.3. Operation. During the Operation Phase, the software is maintained, evaluated, 
and changed as additional requirements are identified. 

1 3 Stages While the terminology used to describe the stages is arbitrary, it provides a con- 
vPniPnt^Siework within which the development of the ten document types may be discussed. 

coTnS that no? all of the document types are required to f°™^,^^^^^^^^^^ 
case and that in some cases the various document types may need to be combined. The flexible 
nature of these guidelines is discussed in Part 2. 
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Definition. During tlie definilioii slafre. the i-eciuirenients for Die soft\viii-e ami docu- 
mentation are dolcrmini'd. Tiio Fimcti..na). KcMiiirenK'iUs Document and tho Data Jloqmve- 
nients Docunient may l)e lu-epared. 

1 3 2 Desijrn Dm-inu- llu- dfsign staj-v. tiie design alternatives, specific requirenients, and 
functi..ns to be perfornu'd are anai>7.od an<l a design is specified. Documents wiuch may be 
prepared include the System Subsystem Specification. Program Si)ecification, Data Hast 
Specification, and Test Plan. 

1 Pnisframming. During the prMgrannuing stage, the software is coded and (lebugged. 
Documents which n.ay be prepared during tiiis stage ii.cUide the Users Manual. Operations 
Manual. Program Maintenance Manual, and Test Plan. 

1 3 .1 Tost. During the test stage, the software is tested and related documentation re- 
viewed. The software and documentation are ev.nluated in terms of readiness tor implementa- 
tion. The Test Analysis Ueiwrt may be prejiared. 

DocunK-ni Types. The purpose of each of the ten document tyjies. described in further detail 
part is ilcliiied in the following paragraphs. 

! 4 1 Functional Kequ'-remenis Document. The purpose of the Inmctional Requirements 
Document is to provide a basis for tiie mutual understanding between users and designers 
of the initial definition of the .software, including the requirements, operating environment, 
and development plan. 

1..1.2. Data Requirements Document. The purpose of the Data Requirements Docunient is 
to provide during the definition stage of software development, a data description and tech- 
nical information about data collection requirements. 

1.1.1 Sv.slem/Subsvstcm Specification. Tlie purpose of the System/Subsystem Spcrifica- 
tion"is to specify for analysts and programmers the requirenients. operating environiuent. 
(le!"gn cSar'icteristics. and program specifications (if desired) for a system or subsystem. 

1..J..I. Program Specification. The purjiose of the Program Specification is to specify for 
programnicM-s the requirements, operating environment, and design characteristics of a com- 
puter program. 

1.4.-,. Data Base Specification. The purpose of the Data Base ^^'ff^'^^^^^^^^^^^ 

tiie identification, logical characteristics, and physical characteristics of a paiticulai data base. 

1 A fi Users Manual. The puriiose of tho Users Manual is to sufficiently describe the func- 
ions performed bv the softwa I'e in non-ADP terminology, such that the user organization can 
Srn le itTlw icability and when and how to use it. It should serve as yefei^^ce docu- 
ment for preparktion of input data and parameters and for interpretation of lesuits. 

1 .1 7 Ooerations IVlanual. The purpose of the Operations Manual is to provide computer 
Jpenai-HMieS^^^ ^itli a description of the software and of the operational environment 
so that the .software can be run. 

1.4.8. Program Maintenance Manual. The purpose of the Program Maintenance Manual is 
to provide the maintenance programmer with the information necessary to undeistand the 
programs, their operating environment, and their maintenance procedures. 

1 4 9 Test Plan The purpose of the Test Plan is to provide a plan for the testing of 
.Ufware? detailed specitoitic^is. descriptions, and procedures for all tests; and test data re- 
duction and evaluation criteria. 

1 4 10 Test Anaiy.sis Report. Tlie purpose of the Test Analysis Report is to document the 
fett nnilvsis res I ts and findings, present the demonstrated capabilities and deficiencies foi 
mlw"'^^^^ bLsis for prtparing a statement of software readiness for implementa- 

tion. 
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PART 2. DOCUMENTATION CONSIDERATIONS 

Doc'unionlalion pivpai-ation should trt^iUvl as a conlinuinji' cd'ort, evolving- IVoni prelimin- 
ary (Iral'ts, Ihroujib changes and ri'vifus. to tin* (locuniciital i(>ii and s(>rt\vai'o doliviM-ed. Tin* ox- 
tLMil of (lorunioidalion Id he proparcnl is a funrtioii of a^^nu'v niaiiaj^enuMit pi*a('tic(\^ and tlu^ siz(\ 
foMipl(»xily and I'isk of llu» i^rojtH't. 

2.1. Responsil)ilitics. Sepai ahlc res])i)nsil)ilities which are inhtM-(»nt in the llexibk' natni*t?of Uu'se 
Kuidolinos are: 

a. Defmilidn of ai^vncy •^iiidanee to prefect nianaj^ers as to what (huunienlal ion sh<aihl be 
prepared undei* various conditions and. i^erhaps. to what hnels of extent, detail, and foi'inality. 
See Kxaniiih\s A and B in jiaragi'aph li.o. 

I). Determination ))y a project nianaKf^' the (h)cinn(Mitation phm foi' a specific i)i-oject, in- 
cliidin^^: 

(1) What document tyi)es apply and should l)e i)i-oi)ared. 

(2) The foi-mality. extent, and detail of the documentation. 

(:^>) Uesponsibilities and a schedule of i)repai-ation for the documentation, 
(1) Mroceduies and schedule of I'cview, api)i-(n'al, and disti'ibution and the distribution list, 
(o) Resp(»nsil)ilities foi- documentation main tenance and chanj^e conti'oj throu^^h the develop- 
ment phase. 

Th(» foi-mality. extent, and lev{'l of detail, and other detei-nunations by the project manager in 
specific cases will be moi'e consistent if agency guidance and ci'iteria ai'e established. Tn pfeneral, 
as the size, comph>xity. and risk of a ])roject increase, so does the need for foi'mality, extent, and 
level of detail of the docum{Mitation. Tlie Users. Opei'ations, and I'ro^ram Maintenance Manuals 
shoidd be foinial since they sui:>port the use of tile softwai'e^ particularly if the software will be 
used outside of the devoh^pin^- oi-^anization oi- if extensive changes '<\\v exi^ected during the life 
of the .software. 

2.2 Porumenl .Audiences. Each document tyi)e is written Cora particular ''andience." Th(^ au- 
dience may be an individual or a S'roiip of individuals who are expected to use the document con- 
tents to pei-form a function, e.^r.. operation, maintenance, desipfn. pi'og'i-ammin^. The information 
shoidd be pres(»nted usin^i* the terndnolo^y and level of detail ai)propriate to the audience. 

2.:i. Redundancy. The ten document types in this guideline have some appai'ent redundancy. 
This api)aient redundancy is of two types. Introductory material has been included in each docu- 
ment type to provid(^ the i-eader with a frame of reference. This information has been included 
to provide the *\stand alone*' ai^proach, and und<-irstandino- of the document with a minimum need 
foi* cross-refei-encinjr to pails of other documents that may have been produced. A second type 
of ;i])])arcnt re(lundancy is lluit n^ost document types specify, for example, de.'^^criptions of inputs, 
outputs, and ecpnpmen't to he includinl. The information that should be included in each of the 
document types, diflers in context and, perhaps, in terminology'- and level of detail, since the in- 
formation is intended to be read by different audiences and at different points in the software 
life cycle. 

2.4. Flexibility. Flexibility in the use of the document content fifuidelines is provided by the ba- 
sic orj^anixation of contents. An attempt has l)een made to provide an internally consistent orga- 
nization sclieme. The following^ paragraphs descril)e various options which should be considered. 

2.4.1. "Sizing" of Document Types. Each document type outline may be used to prepare 
documents that range from a few to several hundred pages in length. The size depends on 
the size and complexity of the project and the judgment of the project manager as to the 
level of detail necessary for the environment in which the software will be developed or run. 

2.4.2. Comhining and Expanding Document Types. It is occasionally necessary to combine 
several document types under one cover or to nroduce seve»'al volumes of the same document 
tvpe. Document types that can be combined into one are, for example, the Users, Operations, 
and Program MaintiMiance Manuals. When this is done, the substance of the contents covered 
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])y I'arli tlocunuMit type sliouhl \>v i)ri*s(.Mito{| usiii^' iho oiilliiu' of that docuiuoiit type, for exam- 
ple, Part I Tsers, l*arl 11 Operations, atul I'ai't 111 J'roy-i'am iMaiiileiiance. 

When a system is extremely lar^>i' or is to i)e documented in a modular fashion, a docu- 
ment may i.)e pre])ared for each niodule. In some cases, the size of a document may necessi- 
tate that* it he issued in midtiple volumes to allow ease of usei' i-efei'ence. In such cases, the 
d(jcunient should he separated at a section division. The contents of the Test Plan document 
tyi)e. for example, may he separated hotween the sections of plan, specifications and evalua- 
tion, and specific test descriptions. 

2.-IJi. Formal. Tlu» content Kindelinos in Part :^ have heen prepared usin^r a [generally con- 
sistent format. Use of this jJarticulav format is encouraged hut is not essential. It* is a tested 
and accepted format. 

2.-I.-I. Sequencing? of Contents. In Kc'neral, the order of the sections and paragraphs in a 
particular document type slu)id(l he the .same as shown in the content i»uidelines in Part 3. The 
oi'dtM- may he changed if it significantly enhances the presentation. 

2. 1.5. Documenting IMultiple Programs or IMultiple Files. Many of the document type con- 
tent (Uitlines anticipate and are adaptahle to documenting a system and its .subsystems, multi- 
ple programs, or niultii)Ie files. All of those outlines can, of course, be used for a single sys- 
tem, subsystem, program, data base, or file. 

2.1.6. Section/I*aragraph Titles. In general, the titles of sections and paragraphs should 
be the .<;anie as shown in the content guidelines. The titles may be modified to reflect ter- 
minology uni(iue to the software being documented if the change significantly enhances the 
presentation. Sections or paragraphs may be added or deleted as local requirements dictate. 

2.4.7. Expansion of Paragraph.s. Many of the document types have paragraphs with a gen- 
eral title and a list of factors that niiglit be discussed within tli'U paragraph. The intent of 
^lie content guidelines is not to prescribe a discussion of each of these items, but to suggest 

j^hii\ these items be considered in writing that paragi'aph. These and all other paragraphs 
may he expanded and further subdivided to enhance the presentation. 

2.-I.8. Flowcharts/Deci.sion Tables. The graphic representations of some problem solutions 
are treated best in the fonn of flowcharts, others in the form of decision tables. Either may 
be included in or appended to the documents produced. 

2.4.9. Forms. The use of .specific forms is dependent on practices in an agency. Some of the 
information specified in a paragraph in the content guidelines may be recorded on such forms. 
If so. the form can be referenced from the appropriate paragraph. Tlie use of standard forms 
is encoui*aged. 

2.5. Examples of Documentation Guidance and Criteria. The formality, extent, and level of de- 
tail of documentation to be prepared is a function of agency ADP management practices and the 
size, comp-exity. and risk of a project. The following examples were taken from two Federal 
agencn (iirectives, but are amended to conform to the naming of document types in this publica- 
tion. The examples illustrate how criteria could be established to aid project managers in deter- 
mining the extent and level of detail of documentation required. 

Example A presents a scheme using development cost and document audience as two criteria 
to establish thresholds for documentation requirements. See the following pages and Figure 
2. 

Example B presents a scheme using twelve criteria with weighting factors and a scale of the 
total weighted criteria to establish formal documentation requirements. Figure 3 illustrates 
the application of the weighted criteria shown in Figure 4. The procedure to use these tables 
is: 

1. Weight the softwai'e by each of the twelve criteria in Figure 4. 

2. Sum the weights assigned. (Total weighted criteria.) 

3. Find the row in Figure 3 that lists the document types to be prepared. 
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Figure 2. EXAMPLE A. Cost uml/or ttsagc tkrcskold criteria for vytctit ami formalitij 



LevoJ 



If PROJECT COST 



Le.<s than $1000 
Or 

One Man-month 
$1000 to $5000 



Over $5000 



Ovrr $5000 



Or USAGE 



One Shot 
(Sin^lo Use) 



Special or 
liimited 
Purpose or 
Application 

Multipurposed. 
or Multiuser 



Publicly 

Announced, or 
Critical to 
Operations 



Thon DOCUMENTATION 
ELEMENTS 



Software Summary plus any 
incidentally produced docu- 
mentation. 

Level 1 plus Users Manual 
and Operations Manual. 



Lovt'l 2 plus Functional Re- 
(juirenients Document, Pro- 
^rram Specification, Pro- 
pram Maintenance Manual, 
Test Plan, Test Analysis 
Report, and System/Suh- 
systLMii Specification. 

Lfvel 3 produced in a form 
suitaltlo for publication. 



Ami EXTENT OF EFFORT 



No special effort, normal j2:ood prac- 
tice. 

Minimal documentation effort, spent 
on informal documentation. No for- 
mal documentation effort. 



All basic elements of documentation 
should be typewritten* but need not 
be prepared in finished format for 
publication or require external edit 
or review. 



At a minimum, all basic elements pre- 
pared for formal publication,^ in- 
eludinjx external reviev.- and edit. 



EXAMPLE A. LEVELS OF DOCUMENTATION 



DEFLMTIONS OF LEVELS 

documentation 
(1) 

mTninial'"levei;72)" int^^^^^^^^^ (3) working document ' level, and (4) formal publication level. 



T. 

lias be 



o protect against both over and under documentation, computer program documenta 
Beii divided into four levels. From lowest to highest these levels of documentation aie. 



Tl ^ criteria determining 'these levels of documentation are described in the following paragraphs, 
and summarized in Figure 2. Additional criteria peculiar to an installatioii and/or jud^^^^^ 
tive to program sharing potential, life expectancy, and usage frequency are also appiopnate lac- 
tors to be considered in the determination of documentation levels, 

MLVLMAL LEVEL (LEVEL 1) 

Level 1 documentation guidelines are applicable to single ''^^ I'^'^'.^^'f^^^^^ 
minimal complexity. Although no significant documentation cost sliouUi be added, theie exists the 
mu irement to show what type of work is being produced and what a given program really does. 
S c s it is desirable to keep on file for a minimum period of time the documentation which re- 
sults from the development of the programs, i.e., program abstract, compile listing test cases etc^ 
The criteria for categ(n-izing a program as Level 1 can be its expected usage or the esource ex- 
S^S S its g^^^^^^ or dollars, and may be modified for the peculiar require- 

ments of the installations. Suggested irsource expenditure criteria are programs requiring less 
than one man-nionth effort or less than $1,000 (these are not assumed to be equal). 

INTERNAL LEVEL (LEVEL 2) 

Level 2 documentation applies to special purpose programs which after careful considera- 
tion of the possible interest of others, appear to have no sharing potential and to be designed 
or u.se only by the requesting scientist or manager in an ^"^'l^onmen over which 
nizance. Large programs which have a short life expectancy also fall into this level. 1 he docu- 
Sation required (other than Level 1) is that necessary for deck setup and modifications This 
miSmont Jan be satisfied by the inclusion of detail input/output formats setup instructions 
in he liberal use of comment cards in the source deck to PJ^V^^de clarification in the com^^^^^^^^ 
listing. In summary, the effort spent toward formal documentation for Level 2 programs should 
be minimal. 

~ ,Th. tr~rm -workin. .In.umonf or ►'.orkin^ pnpor- u.H in this ^uUUAiv. wfrr to typcwritt.n ,h,cumcnts not necessarily pr.pnred 
in flninhe^l formal RuiUble for puhlieati.m tun- i^ul.jvct to oMcrnal etlltorial review. 
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WORKING DOCUMENT LEVEL (LEVEL 3) 

This level applies to programs which are expected to be used by a number of people in the 
same installation or which may be transmitted on request to other int^tallations or to contractors 
or grantees. The format of the documentation at this level should include, as a minimum, all ele- 
ments of documentation. All basic elements of documentation should be prepared in typewritten 
form, but not necessarily in a finished format suitable for publication. Normally, it will not be 
formally reviewed or edited above the review required for a working paper. However, if there 
are certain programs important to the activities of the inst<illations, but not considered appro- 
priate for publication, then local more stringent documentation review standards should be ap- 
plied. 

FORMAL PUBLICATION LEVEL (LEVEL 4) 

This level applies to programs which are of sufficient general interest and value to be an- 
ounced outside the originating installation. This level of documentation is also desirable if the 
program is to be referenced by a scientific publication or paper. The format of the documenta- 
tion at this level should comply with the guidelines on elements of documentation suitable for in- 
clusion in one of the scientific and technical publication series with the attendant review and 
editing procedures. 

Al.^o considered to be within this level are those progr.im« which are critical to the activi- 
ties of the installation. These programs should be documented in a formal, rigorous manner, with 
in-depth review and special configuration control procedures enforced. Recurring management 
applications, such as payroll, should be considered for inclusion in this category so as to main- 
tain an accurate history of conformation to changing laws, rules, and regulations. 



P*u;rRK 3. P-X.AMIM.?- B. Tatdl wrif/hfal documcvtatiott criteria vs rvquirvd (hcnment types 
(See Fijrure 1 to rlotermine total woi^hted criteria.) 



























TOTAL 
WEIGHTED 
CRITERIA 


Software 
Summary 


Users 
Manual 


operations 
Manual 


Profrram Maintenance 
Manual 


Test 
Plan 


Functional Require- 
ments Document 


System/Subsyat+im 
Specification 


Test Analysis 
Report 


Program 
Specification 


Data Requirements 
Document 


; Data Base 

1 Specification 


0-12* 


X 






















12-1.5 ' 


X 


X 




















12-2G 


X 


X 


X 


X 


X 














24-38 


X 


X 


X 


X 


X 


X 












36-50 


X 


X 


X 


\ 


X 


X 


X 


X 








48-()0 


X 


X 


X 


X 


X 


X 


X 


X 


X 







NOTE.Sr Additional document types may be required at lower weighted criteria totals to satisfy local 
requirements. 

** The Test Analysis Report logically should be prepared, but may be informal. 
♦** Preparation of the Data Requirements Document and Data Base Specification is situationally 
dependent. 
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EXAMPLE B. Av example of weighting for tirclvv docnvwntatio)} criteria (See Figure :1 for appli- 
\atiiMi of total weighted criteria to ilrtermiuation of required docuinentittwti types.) 



CrjttTia 



1. <»riKinn!ity 
rcquirecl 



DfRr*'** of 
Kcncrnlity 



:t. Sp»n of opcTiition 



ChaiiKC in scope 



Ftjuipmrnt 



6. Personnel 

asrt»jfne<i 

7. r>ev<»Iopniont»l 

cost 

K. rrilicnlily 

I*. Avcrnirc response 
time to projrnini 
chnnRP 

1<» Avorntro rospun^e 
timo to dnta 
inputs 

II. Pn>KrnmminK 



Conctincnt 
Hoftwu rc 
de\*<?l'»pmcnt 



None -rt'proKrnni 
on (UfTcrent 
fqiiipmcnt 

HiKlily rt'>trirto<I. 
SinKti' purp'.tsf 



I.nral or utility 
Nont' 



SihKlo machine 
ItiKiliin' 
prtn**'<«it>R 



1 ink 



l>ata procfSsinK 
11 (tr more weeks 



2 or nmrr weeks 



I!i>:h level 
ktuKuaKC 



None 



Minimttm- more 
«trinKent 
re«iuirement!* 

Ke.«l rictei! — parameter- 
i/.eil for a ranse of 
capacities 



Component command 
Infrequent 



SinKle machine, Uontine 
proces.-*inK. Kvtentteil 
peripheral >iy!iteni 



3-5 
If) r>Ok 

Routine operation!* 
1 'J week? 



WEIGHTS 



I.iniite<I — new 
interfaces 



1 2 weeks 



JIiKh level anti limited 
asscmtity lanKunKC 



I.imitAxI 



l.imiteil flexibility. 
Allows somecI.'inKo 
in format 



Siittrle command 
Occasional 



MultiTompiitor. 
Standard peripheral 
«yj*tem 



R-iO 

r)0 ^noii 

I*ersonnel nafety 
7 (lays 

1 7 days 



HiKh level and ex- 
lennive asHcmldy 
lanKOHKe 



Moderate 



Considerable — apply 
eNifitinK state of art 
to environment 

Multi-purpose. KleNible 
format. HanRe of 
subjects 



M ulti-conimnnd 



Frequent 



Multi-computer Ad- 
vanced proKrnmmlnR. 
Complex peripheral 
syntem 

10-18 



200 nook 

Unit survival 
1 :\ dayn 

1 21 hours 

A-s5emii)y lanRiinKe 

Kx tensive 



Kxtenftive— requires 
advance in state of 
the art 

Very flexible — able to 
handle a broad 
ranKe af subject 
matter on dilTerent 
equipment 

Defenf^e Department. 
WorM wide. 

Continuous. 



Master control nystem. 
Midti-oomputer auto 
input/output and 
display efHiipment. 

18 and over 

Over ROOk 

National defense 
1 24 hours 

0 i\f) mi:, jtes 

Machine lanKuntce 

Kxhaustive 
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PART 3, CONTENT GUIDELINES FOR DOCUMENT TYPES 

Part pruvicios content ^-nidelines for the following ten clociinient tyj)es discussed 
in Parts 1 nw 2. 





Functional Requirements Document 




Data Requirements Document 


•\,:) 


System/Suh.-system Specification 


'^A 


Program Specification 


:^.r> 


Data Base Sp^ecificntion 




Users Manual 




Operations Manual 


3.8 


Program Maintenance Manual 




Test Plan 


:M0 


Test Analy '.is Report 



The document types are presented in the order of develoi)ment within the software 
life cycle. Included for each document type are a table of contents and a description of 
the contents of that document type. The page numbers given in the table of contents for 
each document type are those within the boxes. 
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3.1 Functional Requirements Document 
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Tho pui-pose of the Functional RcHiuiromeiits Document is to provide a basis for the 
mutual understancliuK between users and designers of tho initial definition of the soft- 
ware. inchulinK the re(iuirements, operating environment, and development plan. 



Contents 



SKCTION 1- GKNKKAL INFORMATION 



9 



1.1, Summary 

1.2. Environ mi'nt 
RefcrL'nco.s . . 



SKCTIOX 2. OVERVIKW 



2.1. Backj:rountl 

2.2. Objectives .. 

2.3. Existiiij? Methods and Procedures .. 

2.4. Proposed Methods and Procedures 
2.'». Summary of In\provenuM»t.-^ 

2.6. Summary of Impacts 

2.(1.1. Equipment In\pacts 

2.0.2. Software Impacts 

2.f>.3. Organizational I n\ pacts 

2.0.4. Operational Imp^i^^ts 

2.0.5- Development Impacts 

2.7. Cost Consideration.s 

2.5. Alternative Proposals 



SKCTION 3. REQUIREMENTS 



3.1. Functions 

3.2. Performance 

3.2.1. Accuracy 

3.2.2. Validation 

3.2.3. Timing 

3.2.4. Flexibility 

3.3. Inputs-Outputs 

3.4. Data Characteristics 

3.5. Failure Continj^encie.s 



SECTION 4. OPERATING ENVIRONMENT 



4.1. 
4.2. 
4.3, 
4,4. 
4.r,. 



Equipment 

Support Software 

Interfaces 

Security and Privacy 
Controls 



SECTION 5. 



DEVELOPMENT PLAN 
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Functional Requirements Document 



1. GENERAL INFORMATION 

1.1. Summary. Sumiiiarizo the general nature of the software to be developed. 

1.2. Environment. Identify the project .sponsor, developer, user, and computer cen- 
ter or network wlieve the software is to be implemented. 

1.3. Reference.*^. List applicable references, such as; 

a. Project request (autliorizations) . 

I). Previously publislied documents on the project. 

c. Documentation concerning related projects. 

d. FIPS publications and other reference documents. 

2. OVERVIEW 

2.1 Background. Present the purpose and scope of tlie software, and any back- 
ground information that would orient the reader. Explain relationslups with 
other software. 

2.2. Objectives. State the major performance objectives of the software^ includ- 
ing examples. Identify anticipated operational chan^^oc. that will altect the 
software and its i'%e, 

2.:i. Existing Method.s and Procedures. Describe the current methods and proce- 
dures that satisfy the existing objectives. Include information on: 

a. Organizational and personnel responsil)ilities. 

b. Equipment available and required, 

c. Volume and frequency of inputs and outputs. 

d. Deficiencies and limitations. 

e. Pertinent cost considerations. 

Illustrate the existing data flow from data acquisition through its processing 
and eventual output. Explain the sequence in which operational functions are 
performed by the user, 

2.4 Proposed Methods and Procedures. Describe the proposed software and its ca- 
pabilities Identify techniques and procedures from other software that will be 
used or that will become part of the proposed software. Identify the require- 
ments that will be satisfied by the proposed software. Include infomation on: 

a. Organizational and personnel responsibilities, 

b. Equipment available and required. 

c. Volume and frequency of inputs and outputs. 

d. Deficiencies and limitations. 4.- n 

e. Pertinent cost considerations (developmental as well as operational). 

Illustrate the proposed data flow to present an overall view of the planned ca- 
pabilities. Describe any capabilities in the existing software that may be 
changed by the proposed software. State the reasons for these changes, ex- 
plain the sequence in which operational functions are to be performed by the 
user. 
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2,5, Summary of Improvements. Itemize improvements to be obtained from the 
proposed software, such as: 

a. New capabihties, 

b. Upgraded existing capabihties. 

c. Ehmination of existing deficiencies, 

d Improved timehness, e.g., decreased response time or processing time, 

e.' EhminaUon or reduction of existing capabihties that are no longer needed. 

6 Summary of Impacts, Summarize the anticipated impacts of the proposed soft- 
ware on the present system, in the following categories: 

6 1 Equipment Impacts. Summarize changes to currently available equip- 
ment, as well as new equipment requirements and building modifica- 
tions. 

Software Impacts. Summarize any additions or modifications needed 
10 existing applications and support software in order to adapt them to 
tiie proi)osed software. 

2.6.3. Organizational Impacts. Summarize organizational impacts, such as: 

a. Functional reorganization. 

b. Increase/decrease in staff level. 

c. Upgrade/downgrade of staff skills. 

2.6.4. Operational Impacts. Summarize operational impacts, such as modifica- 
tions to: 

a. Staff and operational procedures. 

1), Relationships between the operating center and the useis. 

c. Procedures of the operating center. 

d. Data (sources, volume, medium, timeliness), 

e. Data retention and retrieval procedures. 

f. Reporting methods, 

g. System failure consequences and recovery procedures. 

h. Data input procedures. ^ 

i. Computer processing time requirements. 

2.G.5. Developmental Impacts. Summarize developmental impacts, such as: 

a. Specific activities to be performed by the user in support of develop- 
ment of the proposed software, 

b. Resources required to develop the data base, 

c. Computer .processing -resources required to develop and test the new 
software. 

9 7 Cost Considerations, Describe resource and cost factors that may influence the 
Svelopment! and continued operation of the proposed ^o/tware Discuss 

other fJStor^ which may determine requirements, such as mterfaces with other 
automated systems and telecommunication facilities, 

o o AUo..«nHvi. Pronosik If alternative software has been proposed to satisfy the 
?eqSrS!Sl S each aTtern'ative. Compare and contrast the alternatives. 
Explain the selection reasoning. 
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Functional Requirements Document 



1 



3. REQUIREMENTS 

3.1. Functions. State the functions required of the software in quantitative and 
quahtative terms, and how these functions will satisfy the performance objec- 
tives. 

3.2. Performance. Specify the performance requirements. 

3.2.1. Accuracy. Describe the data accuracy requirements imposed on the 
software, such as; 

a. Mathematical. 

b. Logical. 

c. Legal. 

d. Transmission. 

3.2.2. Validation. Describe the data validation requirements imposed on the 
software. 

3.2.3. Timing. Describe the timing requirements im;)osed on the software, 
such. as, under varying conditions: 

a. Response time. 

b. Update processing time. 

c. Data transfer and transmission time. 

d. Throughput time. 

3.2.4. Flexibility. Describe the capability for adapting to changes in require- 
ments, such as: 

a. Changes in modes of operation. 

b. Operating environment. 

c. Interfaces with other software. 

d. Accuracy and validation timing. 

e. Planned changes or improvements. 

Identify the software components which are specifically designed to pro- 
vide this flexibility. 

3.3. Inputs-Outputs. Explain and show examples of the various data inputs. Speci- 
fy the medium (disk, cards, magnetic tape), format, range of values, accuracy, 
etc. Provide examples and explanation of the data outputs required of the soft- 
ware, and any quality control outputs that have been identified. Include de- 
scriptions or examples of hard copy reports (routine, situational and excep- 
tion) as well as graphic or display reports. 

3.4. Data Characteristics. Describe individual and composite data elements by name, 
their related coded representations, as well as relevant dictionaries, tables, and 
reference files. Estimate total storage requirements for the data and related 
components based on expected growth. 

3.5. Failure Contingencies. Specify the possible failures of the hardware or soft- 
ware, the consequences (in terms of performance), and the alternative courses 
of action that may be taken to satisfy the information requirements. Include: 

4 
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•I B-ick u» Snecifv back-up techniques, i.e., the redundancy available in the 
ev-en he pHmary system element goes down. For example, a back-up tech 
nique for a dSJ medium would be to record periodically the contents of the 

b FaUb^ck ^Txplain the fallback techniques, i.e., the use of another system, 
m other meSs to accomplish some portion of requirements. For example, 
?he fallLTk technlql^^^ automated system might be manual man.pu- 

c R^'cove^f a.?d'Rei?;rt°' Suss the recovery and restart, techniques, i.e. the 
?apTl t^y to resume execution of software from a pomt m Je software sub- 
sejuent to which a hardware or software problem occurred, oi the re-run 
ning of the software from the beginning. 

4. OPERATING ENVIRONMENT 



4.1. 



Fniiinmenl Identify the equipment required for the operation of the software. 
fd'entTy any new equipment required and relate it to specific functions and re- 
quirements to he supported. Include information such as: 

a Processor and size of internal storage. . 

b. Storage, online and offline, media, form, and devices. 

c. Input/output devices, online and offline, 
d Data transmission devices. 

ware', identify the nature and planned date of these changes. 
4.3. Interfaces. Describe the interfaces with other software, 

1 A ^Pruritv and Privacy Describe the overall security and privacy requirements 
fmpo' ed the sSware. If no specific requirements are imposed, state this 
fact. 

4.5. Controls. Describe the operational controls imposed on the software. Identify 
the sources of these controls. 

DEVELOPMENT PLAN 

Discuss in this section the overall management approach^ 
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The purpose of tlie Data Requirements Document is to provide, during: the defini- 
tion stage of software development, a data description and technical infoiTOation about 
data collection requirements. 



Contents 



SECTION 1. GENERAL INFORMATION.. 



2 



2 

1.1. Summary 2 

1.2. Environment - 2 

1.3. References 2 

1.4. Modification of Data Requirements 



SECTION 2. DATA DESCRIPTION 

2 

2.1. Static Data.. 2 

2.2. Dynamic Input Data 2 

2.3. Dynamic Output Data.. 2 

2.4. Internally Generated Datii 2 

2.5. Data Constraints 



SECTION 3. DATA COLLECTION 

3 

3.1. Requirements and Scope 2 

3.2. Input Responsibilities 2 

3.3. Procedures ^ 3 

3.4. Impacts 
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Data Requirements Document 



1. GENERAL INFORMATION 

1.1. Summary. Summarize the general nature of the software for which these data 
requirements are being defined. 

1.2. Environment. Identify the project sponsor, developer, user oi-ganization, and 
computer center where the software is to be instahed. Show the rohitionships 
of these data requirements and those of other software. 

1.3, References. List apphcable references, such as; 

a. Pi-oject request (authorizati(m) . 

b. Previously published documents on the project. 

c. Documentation concerning related i)rojects. 

d. FIPS pul>lications and other reference documents. 

1.4, Modification of Data Requirements. Desci ibe or reference procedures for im- 
plementing and documenting changes to these data requirements. 

2, DATA DESCRIPTION 

Separate the data description into two categories, static data and dynamic data. 
Static data is defined as that data which is used mainly for reference during opera- 
tion and is usually generated or updated in widely separated time frames independ- 
ent of normal runs. Dynamic data includes all data which is intended to be updated 
and which is input during a normal run or is output. Arrange the data elements in 
each category in logical groupings, such as functions, subjects, or other groupings 
which are most relevant to their use. 

2.1. Static Data. List the static data elements used for either control or refer- 
ence purposes. 

2.2. Dynamic Input Data. List the dynamic input data elements which constitute 
the data intended to be changed by a normal run or during onhne operation. 

2.3. Dynamic Output Data. List the dynamic output data elements which consti- 
tute the data intended to be changed by a normal run or during online op- 
eration. 

2.4. Internally Generated Data. List the internally generated data of informational 
value to the user or developer. 

2.5. Data Contraints. State the constraints on the data requirements. Indicate the 
limits of the data requirements with regard to further expansion or utilization, 
such as the maximum size and number of files, records, and data elements. Em- 
phasize the constraints that could prove critical during design and develop- 
ment. 
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DATA COLi.FXTlON 

3 1. Reuuiremenls and Scope. Describe tlie type of iiiformation required to docti- 
menl the chanu'toi-istics of each data element. Specify inforniation to be ool- 
k'cled by the user and tliat to be collected by tlie developer. It should be log- 
ically j^roiiped and presented. Include: 

a Source of Input. Identify the source from which the data will be entered, 
0 an ()poi-al{)r. station, organizational unit, or its component group. 

!. hujul Medium and Device. Identify the medium and hardware deviee in- 
' tended for entering the data into the system. In those cases where only cer- 
liiin special stations are to be legitimate entiy points, they should be .speci- 

V llecipients Identify the intended recipients of the output data. 

rl' Output Medium and Deviee. Identify the medium and hardware device m- 
loniled foi- iiresenting oul|)ut data to the recipient. Specify whether the re- 
cii)icnt is to receive the data as part of a hard copy pnntout, a symbol in a 
CUT display, a line on a drawing, a colored hght, an alarm bell. etc. If the 
output i-. In he passed to some other automated system, the medium shouirt 
be described, such as magnetic tape, punched cards, or an electronic signal 
to a solenoid switch. . , , , .. 

e. Critical Value. One value from a, range of values of data may have particu- 
lar significance to a recipient. . ., r 

f Scales of Measurement. Specify for numeric scales, units of mea.surement. 
■ increments, .scale 7.ero-point. and range of values. For non-numeric scales, 
anv relationships indicated bv the legal values should be stated. 

g Conversion Factors. Spocifv the conversion factors of measured quantities 
' that must go through analog or digital conversion processes 

h Freciuencv of Update and Processing. Specify the expected frequency of 
' data change and the expected frequency of processing input data If the iii- 
S aiTivfs in a random or in an "as occuiTed" manner, both the average 
frequency and some measure of the variance must be specified. 

.3 2 Input Respon.sihilities. Provide recommendations as to responsibilities for pre- 
' ■ paring specific data inputs. Include any recommendations the estab- 

lishment of a data input group. Specify by source those data inputs depend- 
ent on interfacing software or unrelated organizations. 

3 3 Procedures. Provide specific instructions for data collection procedures. In- 
' ' elude detailed formats where applicable, and identify expected data communi- 
cations media and timing of inputs. 

3.4. Impacts. Describe the impacts of these data requirements on equipment, soft- 
ware and the user and developer organizations. 
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The purpose of the System/Subsystem Specification is to specify for Analysts and 
Programmers the requirements, operating environment, design characteristics, and pro- 
gram specifications (if desired) for a system or subsystem. 
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1. GENERAL INFORMATION 

1.1. Summary. Summarize the specifications and functions of the system/subsys- 
tem to be developed. 

1.2. Environment. Identify the project sponsor, developer, user, and computer 
center or network on which the system is to be implemented. 

References. List applicable references, such as: 

a. Project request (authorizations). 

b. Previously published documents on the subject. 

c. Documentation concerning related projects. 

d. FIPS publications and other reference documents. 

2. REQUIREMENTS 

2.1. Description. Provide a general description of the system /subsystem to estab- 
lish a frame of reference for the remainder of the document. Include a sum- 
mary of functional requirejnents to be satisfied by this system/subsystem. 
Show the general interrelationship of the system/subsystem components. 

2.2. Functions. Specify the system/subsystem functions in quantitative and qual- 
itative terms and how the functions will satisfy the functional requirements. 

2.3. Performance, Specify the performance requirements. 

2.3.1. Accuracy. Describe the data accuracy requirements imposed on the sys- 
tem or subsystem, such as: 

a. Mathematical. 

b. Logical, 
c Legal. 

d. Transmission. 

2.3.2. Validation. Describe the data validation requirements imposed on the 
system/subsystem. 

2.3.3. Timing. Describe the timing requirements imposed on the software, 
such as, under varying conditions: 

a. Response time. 

b. Update processing time. 

c. Data transfer and transmission time, 
d- Tliroughput time. 

2.3.4. Flexibility. Describe the capability for adapting the program to changes 
in requirements, such as: 

The orKHnir.Mlion nf the contents of Spction5 2. fl, i, and 5 tnisy vjiry iiccordintr to the p»i'|>o»e of the documentntfon. See 
K>:]irit|ilr folio wink' thix content (cuideltne. pajrc 28. 
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a. Changes in modes of operation. 

b. Operating environment. 

c. Interfaces with other software. 

d. Accuracy and validation and timing. 

e. Planned changes or improvements. 

Identify the system/subsystem components which are specifically de- 
.signed to provide this flexibility. 

3. OPERATING ENVIRONMENT 

3.1. Equipment. Identify the equipment required for the operation of the system/ 
subsystem. Identify any new equipment required and relate it to specific func- 
tional requirements to be supported. Include information, such as: 

a. Processor and size of internal storage. 

b. Storage, online and offline, media, form, and devices. 

c. Input/output devices, online and offline. 

d. Data transmission devices. 

3.2. Support Software. Identify the support software and describe any test soft- 
ware. If the operation of the system/subsystems depends on changes to sup- 
port software, identify the nature and planned date of these changes. 

3.3. Interfaces. Describe the interfaces with other software. 

3 4 Security and Privacy. Describe the overall security and privacy requirements 

imposed on the system/subsystem. If no specific requirements are imposed, 
state this fact. 

3.5. Controls. Describe the operational controls imposed on the system /subsystem. 
Identify the sources of these controls. 

4. DESIGN CHARACTERISTICS 

4.1. Operations. Describe the operating characteristics of the user and computer 
centers where the software will be operational. 

4 System/Subsystem Logic. Describe the logic flow of the entire system/sub- 
system in the form of a flowchart. The flow should provide an mtegrated pre- 
sentation of the system/subsystem dynamics, of entrances and exits, com- 
puter programs, support software, controls, and data flow. 

5. PROGRAM SPECIFICATIONS 

5.1. Program (Identify) Specification. Specify the system/subsystem functions to 
be satisfied by the computer program. 

a. Describe the program requirements. 

b. Describe the operating environment. 

c. Describe the design characteristics of the program includmg mputs, program 
logic, outputs, and data base. 

5.N. Program (Identify) Specification. Describe the remaining computer programs 
in a manner similar to the paragraph above. 

3 
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EXAMPLES OF ALTEIiNATIVE SECTION OUTLINES 

Sections 2, 3, and 4 of this specification may follow one of several alternative out- 
lines depending on the punH>se to which the documentation is directed. Examples of 
alternative puriwses and the corresponding outline are shown below. 

Example A: When this document is directed to the documentation of a given sys- 
tem and is not to specifically include the documentation of any subsys- 
tem, the appropriate title would be **System Specification.'' The outline 
for the specification would be: 

REQUIREMENTS 

Description 

Functions 

PerfoiTnance 
OPERATING ENVIRONMENT 

Equipment 

Support Software 

Interfaces 

Security and Privacy 
Controls 
DESIGN CHARACTERISTICS 
Operations 
Logic 

Example B: When this documents is directed to the documentation of a given subsys- 
tem, the appropriate title would be "Subsystem Specification." The out- 
line for the specification would be the same as Example A above. 

Example C: When Jiis document is directed to the documentation of a system and 
its .subsystems, the appropriate title would be "System and Subsystem 
Specifications." The outline, in brief, for the specification would be: 

Sv^iem REQUIREMENTS 
System OPERATING ENVIRONMENT 
System DESIGN CHARACTERISTICS 
Subsystem 1 (Identify) 

REQUIREMENTS 

OPERATING ENVIRONMENT 

DESIGN CHARACTERISTICS 

PROGRAM SPECIFICATIONS 
Subsystem *n' (Identify) 

Example D: In any of the above examples, the program specifications may be docu- 
mented within as a separate section; as subsections to each subsystem 
section; or may be documented in a separate document, "Program 
Specification/* 
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The |)urp(>se of the Pro-ram Specification is to specify for proirraniniers the require- 
ments, operalin- environment, and design charactei'istics of a computer program. 



Contents 



SECTION 1. GENERAL INFORMATION ^ 

2 

1.1. Summary...- o 

1.2. Environment 2 

1.3. References 

SECTION 2. REQUIREMENTS 



2.1. Program Description 2 

2.2. Functions o 

2.3. Performance o 

2.3.1. Accuracy " 2 

2.3.2. Validation 2 

2.3.3. Timinp: \ \ 2 

2.3.4. Flexibility 

3 

SECTION 3. OPERATING ENVIRONMENT 

3 

3.1. Equipment 3 

3.2. Support Software * 3 

3.3. Interface.*^ 3 

3.4. Storage 3 

3.5. Security and Privacy ^ 

3.6. Controls 

SECTION 4. DESIGN CHARACTERISTICS ^ 

3 

4.1. Operating: Procedures 4 

4.2. Inputs 4 

4.3. Projrram Lopic 4 

4.4. Outputs 4 

4.5. Data Base !****!*^^*!..! 4 

4.5.1 Lojrical Characteristics 4 

4.5.2 Physical Characteristics 
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1. OKNERAL INFORiMATION 

l.L Summary. Summarize the specifications and functions of the computer pro- 
l^ram to be developed. 

1.2. Environment. Identify the project sponsor, developer, user, and computer cen- 
ter where the computer .program is to be run. 

1.3. References. List applicable references, such as: 

a. Project request (authorization). 

b. Previously published documents on the subject. 

c. Documentation concerning related projects. 

d. FIPS publications and other reference documents. 

2, rp:quirements 

2.1. !*rograni Description. Provide a general description of the program to estab- 
lish a frame of reference for the remainder of the document. Include a sum- 
mary description of the system/subsystem functions to be satisfied by this 
program. 

2.2. Functions. Specify the functions of the program to be developed. If the pro- 
gram in itself does not fully satisfy a system/subsystem function, show the 
relationship to other progranis which in aggregate satisfy that function. 

2.3. Performance. Specify the performance requirements. 

2.3.1. Accuracy. Describe data accuracy requirements imposed on the program, 
such as: 

a. Mathematical 

b. Logical. 

c. Legal. 

d. Transmission, 

2.3.2. Validation. Describe the data validation requirements imposed on the 
program. 

2.3.3. Timing. Describe the timing requirements imposed on the program, 
such as, under varying conditions: 

a. Response time. 

b. Update processing time. 

c. Data transfer and transmission time. 

d. Throughput and internal processing time. 

2.3.4. Flexibility. Describe the capability for adapting the program to changes 
in requirements, such as: 
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II. Modes of operation. 

b. Operating environment. 

c. Interfaces with other programs. 

d. Accuracy, vahdation, and timing. 

e. Planned changes or improvements. 

Identify the components of the program which are designed to provide 
this flexibihty. 

OPERATING ENVIRONMENT 

3 1 Equipment. Identify tlie equipment required for the operation of the program. 
Include information on equipment required, such as: 

a Processor and size of internal storage. . 
h Storage, online and offline, media, form, and devices, 
c' Input/Output devices, online and offhne, and capacities, 
d. Data transmission devices. 



3.2. 



3.3 



<3nn««vi <:;,.flware Identify the support software and describe any test pro- 
ImTs If t ror^Va tion of^lSr depends on changes to support soft- 

S, identify the nature and planned date of these changes. 

Interfaces Describe all interactions with the operator. Describe all intei-ac- 
tfons with other software, including sequence or procedure relationships and 
data interfaces. 

3 4 Storage. Six;cify the storage requ.irements and any constraints and conditions, 
storage. 

quirements are imposed, state this fact. 

■^fi Controls Describe the program controls such a.s record counts, accumulated 
count? and ba?ch controls. Identify the sources of these controls. 

DESIGN CHARACTERISTICS 

4.1. Operating Procedures. Describe operating proced^^^^^^^ 
tions of the program with the operator. 
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\.2. Inputs. Provide iiiforniatioii ahout the characteristics of each input to the pro- 
gram, such as: 

a. Title and tag. 

1). Format and type of data, sucli as a record layout. 

c. Validation criteria. 

d. Volume and frequency. 

0. Means of entry. 

f. Source document and its disposition, or specific interface source. 

g. Security and privacy conditions. 

4..3- Program Logic. Describe the program logic. The logical flow should be pre- 
sented in graphic form (flowcharts, decision logic tables) supplemented by nar- 
rative explanations. 

4.4. Outputs. Provide infomiation about the characteristics of each output from 
the program, such as : 

a. Title and tag. 

b. Format specifications, such as a report format. 

c. Selection criteria for display, output, or transfer. 

d. Volume and frequency. 

e. Output media. 

f. Description of graphic displays and symbols. 

g. Security and privacy conditions. 

h. Disposition of products. 

1. Description of sequence of displays, display contents, fixed and variable 
formats, and display of error conditions. 

4..5. Data Base. Describe the logical and physical chai-acteristics of any data base 
used by the program. 

4.5.1. Logical Characteristics. Describe for each unique set, file, record, ele- 
ment, or item of data, its identification, definition, and relationships. 

4.5.2. Physical Characteristics. Describe in teiTns of this data base, the stor- 
age requirements for program data, specific access method, and physi- 
cal relationships of access (index, device, area), design considerations, 
and access security mechanisms. 
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The purpose of the Data Base Specification is to specify the identification, logical 
characteristics, and physical characteristics of a particular data base. 



Contents 

PiiKe 
2 

SECTION 1. GENERAL INFORMATION 

2 

1.1. Summary 2 

1.2. Environment 2 

1.3. References * 

2 

SECTION 2. DESCRIPTION 

2 

2.1. Identification 2 

2.2. Using Software 2 

2.3. Conventions 2 

2.4. Special Instructions 2 

2.5. Support Software 

SECTION 3. LOGICAL CHARACTERISTICS - ^ 

SECTION 4. PHYSICAL CHARACTERISTICS ^ 

3 

4.1. Storage 3 

4.2. Access 3 

4..'?. Design Considerations 
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1. (;enkkal information 

Ll. Summary. Summai-ize the puvpose of tlio data base and general functions of 
tlie u?^ing' software. 

1.2. Environnieni. Idemify llie project .sponsor, developer, usei' organization, and 
computer center where the software and data l)ase are to l)e installed. 

References. Ms( appiical'le references, such as: 

a. Pn)jecl request (autliorization) . 

I). I^reviously publislied documents on the i)i'oject. 

c. Documentation concei-ning relaterl projects. 

(1. FIPS publications and other reference documents. 

2. 1)KS( RIPTIO.N 

2.1. Idendficalion. Specify tlie code name, tag, or label by which the data base is 
to be identified. Jf tlie flata base is to be expeiimental, test, or temporary, spe- 
cify tliis cliaracteristic and effective dates (^r period. Any additional identifi- 
cation information should also be given. 

2.2. Using Software. Identify all softwai'e intended to use or access this data base. 
Identify for each: tlie software name, code name, and any release or version 
number. 

2.^^. ('onventions. Descrilje all labeling or tagging conventions essential for a pro- 
grammer or analyst to use tiii.s data base specification. 

2.4. Special Instructions. Provide any si)ecial instructions to personnel who will 
contril>ute to the generation of the (lata base, or who may use it for testing or 
operational purposes. Such instructions include criteria, procedures, and for- 
mats for: 

a. Sui)niitting data for entry into the data base and identification of a data con- 
trol (U'ganization, 
1). Entering data into the data base. 

Where these instructions are extensive, reference appropriate sections of other 
documents. 

2.5. Support Software. Describe l)riefly all support software directly related to the 
data base. Descriptio^r.s should include name, function, major operating char- 
acteristics, and machine run instructions for using the support software. Cite 
the support software documentation by title, number, and appropriate sections. 

Examples of support software are: 

a. Data base management systems. 

b. Storage allocation software. 

c. Data base loading software programs. 

d. File processing programs. 

e. Other generating, modifying, or updating software. 
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3. LOGICAL (HARACTEKISTICS 

A data base is a logical arrangement of data. Sets (aggregates), files, I'f o?'ds. elo- 
■nienls m l items of duta may vary in their logical arrangement and i;ela .onsh.p.. 
The ui'^anizatic.n of tlu> c.ntonl of this section should provide a meanmgful p.esent- 
ation of the logical organization of the data base. 

Define each unique set (aggregate), file, record, element, or item of data providing 
information, such a.s: 



a. 

b 



Identification. Name anil tag, or label. . , , .„ ^ffwnrn- mprliM- 

Definition. Standard or unique: purpose m data base; usmg ^of t« aio media 
form; format and size; update criteria and '••o"^'^'"''-' ^ "^PV'^,'^ ' 
strict ons, limitations, or conditions (update, or acce.«s) ; 'l^-^..^^'' 
ch'u-icter sties - controlling data elements or Hems; and gi-aphic repi esentation. 
RSiionshlpi ' S^ iul-erior relationships; update and access relation- 

ships. 



4. PHYSICAL CHARACTERISTICS 

4.L Storage. Specifv the storage requirements for the data base and any con- 
straints and con(^itions. 

•I Internal Describe s nd illustrate the use of internal storage areas set aside 

" 0 daJa incSig indexing --^^ -■0^^^-^^^%''^^^^^^^ 

constraints and desini considerations that affect the use of '"tei ' al stoiage^ 

b Device List by dev.ce type all peripheral storage required for the data 
base Briefiv state anv contraints imposed on storage requirements by each 
storage device State requirements for permanent data storage and tempora- 
vAi-v data storage, including overlays. , , r u «ffi;„o 

0. Offline Describe the form: media and storage requirements of all offline 

data storage. 

Access Describe the access method and specify the physical relationships of 
Access (index, ifvice area). Describe all physical access security mechanisms. 

Design Considerations. State the design considerations for the handling of 
tliis data base, such as bloc'ung factors. Eniphasize those physical relation- 
ships important to the efficient utilization of the data base. 



4.2 



4.3. 



Sec Examplr. of O.ntcr.t OrcHniw.l.nn for Soction n on pngv W. 
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EXAMPLES OF CONTENT ORGANIZATION FOR SECTION 3 



Example A: Simple structure in uiiicli the data base is coniposed only of data elements: 

Element 1 (Identification, Definition, Relationships) 
Element 2 (Identification, Definition, Relationships) 
. Element N (Identification, Definition, Relationships) 

Example B: Simple hierarchial structure in which the data base is composed of files, rec- 
ords, and data elements: 

File 1 (Identification, Definition, Relationships) 

Record 1 (Identification, Definition, Relationships) 

Element 1 (Identification, Definition, Relationships) 
Element N (Identification, Definition, Relationships) 
Record N (Identification, Definition, Relationships) 
File N (Identification, Definition, Relationships) 

Example C: A sti-ucture in which a data base is composed of data elements and sets 
of data with an oi'ganization based on multiple or specific relationships be- 
tween elements and sets: 



Element 1 (Identification, Definition, Relationships) 
Element N (Identification, Definition, Relationships) 

Set 1 (Identification, Definition, Relationships) 
Set N (Identification, Definition, Relationships) 

Example D: Any of the above structui'es, but with a substantial number of sets, files, 
records, elements, or items of data. Outline in graph or chart form the 
structui-e, levels, and relationships with each chart element denoting the 
Identification of the set, etc., portrayed. Supplement the graph or chaii 
with a suitably organized listing of all sets, etc., with the appropriate Def- 
inition and Relationships information. 
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The purpose of the Users Manual is to sufliciently describe the functions performed 
bv the software in non-ADP terminology, such that the user organization can determine 
its applicability and when and how to use it. It should serve as a reference document for 
preparation of input data and parameter, and interpretation of results. 


Contents 
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1. GENERAL INFORMATION 

1.1. Summary. Summarize tlie appii(!ation and general functions of the software. 

1.2. Environment. Identify the user organization and computer center where the 
software is installed. 

1. :i. References. List applicable references, such as: 

a. Project request (authorization). 

b. Previously published documents on the project. 

c. Documentation concerning related projects and software. 

d. FIPS publications and other reference documents. 

2. APPLICATION 

2. L Description. Desci'ibe when and how tho software is used and the unique sup- 

port provided to the user organization. The description should include: 

a. Purpose of the software. 

b. Capabilities and operating improvements provided. 

c. Functions performed. 

2.2. Operation. Show the operating relationships of the functions perfoi-med to 
the organization that provides input to and receives output from the software. 
Describe security and privacy considerations. Include general charts and a de- 
scription of the inputs and outputs shown on the charts. 

2.3. Equipment. Describe the equipment on which the software can be run. 

2.4. Structure. Show the structure of the softw^are and describe the role of each 
component in the operation of the software. 

2.5. Performance. Describe the performance capabilities of the software including 
where appropriate: 

a. Quantitative information on inputs, outputs, response time, processing times, 
and error rates. 

b. Qualitative information about flexibility and reliability. 

2.6. Data Base. Describe all data files in the data base that are referenced, sup- 
ported, or kept current by the software. The description should include the pur- 
pose for which each data file is maintained. 

2.7. Inputs, Processing, and Outputs. Describe the inputs, the flow of data through 
the processing cycle, and the resultant outputs. Include any applicable relation- 
ships among inputs or outputs. 
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3. PROCEDURES AND REQUIREMENTS 

This section should provide information about initiation procedures and Pi-fP'!™- 
tio fof data and parameter inputs for the software. The scope, quality, and log cU 
am\ngeme;>t of the infornnition should enable the "^^^ ^o prepare required np s 
and should explain in detail the characteristics and meaning of the outputs. It snouin 
also de.scribe error, recovery, and file query procedures and requirements. 

.3.1. Initiation. De.scribe .step-by-si procedures required to initiate processing. 

.3.2. Input. Define the requirements of preparing input data and parameters. T.vpi- 
cal con.siderations are: 

;i Conditions--e.g., personnel transfer, out of stock. 

i,: Frequency-e.g., periodically, randomly, as a function of an operational .sit- 

nation. o i. i 

c Origin e g , Personnel Section, Inventory Lontrol. 

(i Medium— e.g., l<eyboard, punched card, magnetic or paper tape. 

e Uestrictions-e.g.; priority and security handling, limitations on what files 

mav be accessed I'y this type of transaction, 
f Oulilitv control— e.g., instructions for checking reasonableness of input data, 

Son to be t:Sa>n when data appears to be in error, documentation of e.Tors^ 
g. Disposition— e.g., instructions necessary for retention or release of all data 

files received, other recipients of the inputs. 

3 2 1 Input Formats. Provide the layout forms used in the initial P/'epa>-iition 
program data and parameter inputs. Explain each entry, and refeience 
ft tf the imple foi-m. Include a description of the grammatical rules 
and conventions used to prepare input, such as: 

a. Length— e.g., characters/line, characters /item. 

b. Format— e.g., left justified. 

c Labels — e.g., tags or identifiers. • • (. 

d Seauence— e.g., the order and placement of items in the input, 
e! Su"aUon-e.g., spacing and use of symbols <vir^ule, aster^^^^ 
character combinations, etc.) to denote .'■■tart and end of input, of lines, 

f CombilaUoi-e.g^rules forbidding use of groups of particular char- 
acters, or combinations of parameters in an input. U .,„(-oV 
e Vocabulary-e.g., an appendix which lists the allowable character 
^' corSbinations or codes that must be used to identify or compose in- 

h. Omissions and Repeats-e.g., indicate those elements of input that 

that are optional or may be repeated, 
i. Controls— e.g., header or trailer control data. 

3.2.2. Sample Inputs. Provide specimens of each complete input form. In- 
clude: 

a Control or header-e.g., entries that denote the input class or type, 

date/time, origin, and instruction codes to the software. . 
b Text— e g. subsections of the input representing data for operation- 
■ al files request parameters for an infomation retrieval program. 
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c. Trailer— control flata denoting' the end of input and any addi- 
tional control data, 

d. Omissions — e.g., indicate those classes or types of input that may 
be omitted or are optional. 

e. Repeats — e.g*., indicate those positions of the input that may be re- 
peated. 

3.3. Output. De.scribe the i-equirements relevant to each output. Typical considera- 
tions are: 

a. Use — e.g., by whom and i\)v what. 

b. Frequency — e.g., weekly, periodically, or on demand. 

c. Variations — e.g., modifications that are available to the basic output. 

d. Destination — e.g., computer area, remote terminal. 

e. Medium — e.g., printout, CRT, tape, cards. 

f. Quality control — e.g., instructions for identification, reasonableness checks, 
editing and error correction. 

g. Disposition — e.g., instructions necessary for retention or release, distribution, 
transmi.ssion, priority, and security handling. 

3.3.1. Outi)ut Formats. Provide a layout of each output. Explanations should 
be keyed to particular parts of the format illustrated. Include: 

a. Header — e.g.. title, identification, date, number of output parts. 

b. Body — e.g., information that appears in the body or text of the out- 
put, columnar headings in tabular displays, and record layouts in ma- 
chine readable ouputs. Note which items may be omitted or repeated. 

c. Trailer — e.g., summary totals, trailer labels. 

3.3.2. Sample Outputs. Provide a sample of each type of output. For each 
item on a sample, include: 

a. Definition — e.g., the meaning and use of each information variable. 

b. Source — e.g., the item extracted from a specific input, from a data 
base file, or calculated by software. 

c. Characteristics — e.g., the presence or absence of the item under cer- 
tain conditions of the output generation, range of values, unit of 
measure. 

3.4. Error and Recovery. List eri-or codes or conditions generated by the soft- 
ware and corrective action to be taken by the user. Indicate procedures to be 
followed by the user to ensure that any restart and recovery capability can 
be used. 

3..5. File Query. Prepare this paragraph for software with a file query retrieval ca- 
pability. Include detailed instructions necessary for initiation, preparation, and 
processing of a queiy applicable to the data base. Describe the query capabili- 
ties, forms, commands used, and control instructions required. 

If the software is queried through a terminal, provide instructions for termi- 
nal operators. Describe terminal setup or connect procedures, data or param- 
eter input procedures, and control instructions. Reference related materials de- 
scribing query capabilities, languages, installation conventions and procedures, 
program aids, etc. 
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The purpose of the Operations Manual is to provide computer 
nel with a description of the .software and of the operational environment so that the 
software can be run. 



Contents 



SECTION 1. GENERAL INFOIOl ATION. 



2 



2 

1.1. Summary """^ 2 

1.2. Environment ' 2 

1.3. References 

2 

SECTION 2. OVERVIEW 

2 

2.1. Software Or^canixation ' 2 

2.2. Program Inventory 2 

2.8. File Inventory 

2 

SECTION 3. DESCRIPTION OF RUNS 

2 

3.1. Run Inventory 2 

3.2. Run Progression 2 

3.3. Run Description (Identify) ■■■' '** 2 

3.3.1. Control Inputs 2 

3.3.2. OperatinK Information 3 

3.3..3. Input-Output Files * /"y/^^".'.^'^!*^ 3 

3.3.4, Output Reports 3 

3.3.5. Reproduced Output Reports ' . 3 

3.3.G. Restart/ Recovery Procedures 7.^ ^ 

3.4. Run Description (Identify) 

..3 

SECTION 4. NON-ROUTINE PROCEDURES 

.... 3 

SECTION 5. REMOTE OPERATIONS 
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Operations Manual 

GEiNERAL INFORMATION 

1.1. Suninmry. Summarize llie general functions of the software. 

1.2. Environments. Identify the software sponsor, developer, user or^^^anization, and 
the computer center wliere tlie software is to be installed. 

1.3. References. List applical)le references, such as: 

a. Project request (authorization). 

I). Previously published documents on the project. 

c. DocumentJition concerning related projects. 

d. FIPS publications and other reference documents. 

OVERVIEW 

2.1. Software Or«:aniziition. Provide a diagram showing the inputs, outputs, data 
files, and sequence of operations of the software. Runs may be grouped by 
periods of time cycles, by organizational level where they will be performed, 
or by other groupings. 

2.2. Program Inventory. Identify each program by title, number, and mnemonic 
reference. 

2.3. File Inventory. Identify each permanent file that is referenced, created, or up- 
dated by the system. Include the title, mnemonic reference, storage medium, 
and required storage. 

DESCRIPTION OF RUNS 

3.1. Run Inventory. List the various runs possible and summarize the purpose 
each run. Show the programs that are executed during each run. 

Run Progression. Describe the manner in which progression advances from 
one run to another so that the entire run cycle is completed. 

Run Description (Identify). Organize the infoi-mation on each run into the 
most useful presentation for the operating center and operations personnel in- 
volved. 

3.3.1. Control Inputs. List the run stream control statements needed for the 
run. 

3.3.2. Operating Information. Provide information for the operating center 
personnel and management, such as: 

a. Run identification. 

b. Operating requirements. 

c. Initiation method, such as on request, at predetei-mined time, etc. 

d. Estimated run time and turnaround time. 

e. Operator commands and messages. 

f. Contacts for pi-oblems with the run. 



3.2. 
3.3. 
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3.3.3. Input-Output Files. I'n.vide inforniation for files created or updated 
i)y the run. such as: 

a. File name or label. 

b. Recording medium. 

c. Retention schedule. 

d. Disposition of file. 

3.3..1. Output Reports. For each output report or type of report, provide in- 
formation such as: 

a. Report identification. 

b. Medium. 

c. Volume of report. 

d. Number of copies. 

e. Distribution. 

a. Report identification, 
b Reproduction technique. 

c. Dimensions of paper or other medium. 

d. Binding method. 

e. Distribution. 

3.3.6. Re.start/Recuvery Procedures. Describe procedures to restart the run or 
recover from a failure. 
, Run De-scription (Identify). Present inforn.ation about the subsequent runs in a 
manner similar to that used in paragraph 3.3. 



NON-ROIJTINE PROCEDURES 



'p,„viao .ny information noccw co„cen,i,.. cmevgcncv or „.>„-,o„tine ope,.tio„., 

such as: 

KEMOTE OPERATIONS 

Describe the P.«e=<iu.es for .nnnins ll,e „r„g,an,. through remote ter„„„.nls. 
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The purposc> of the Program Maintenance Manual is to provide the maintenance pro- 
granm^er witiru necessary to understand the programs, then- operating 

environment, and their maintenance procedures. 



Contents 



SECTION 1. GENERAL INFORMATION. 



1.1. Summary 

1.2. Environment.. 

1.3. References 



SECTION 2. PROGRAM DESCRIPTIONS. 



2.1. Program (Identify) Description. 

2.1.1. Problem and Solution Method. 

2.1.2. Input 

2.1.3. Processing: 

2.1.4. Output 

2.1.5. Interfaces 

2.1.fi. Tables 

2.1.7. Run Description 



2.2. Program (Identify) Description.. 



SECTION 3. OPERATING ENVIRONMENT.. 



3.1. Hardware 

3.2. Support Software 

3.2.1. Operating? System 

3.2.2. Compiler/ Assembler... 

3.2.3. Other Software 

3..3. Data Base 



SECTION 4. MAINTENANCE PROCEDURES.. 



4.1. 
4.2. 
4.3. 
4.4. 
4.5. 



Proj^ramminjLC Conventions 

Verification Procedures 

Error Correction Procedures 

Special Maintenance Procedures.. 
Listin^:^: and Flowcharts 



2 



2 
2 
2 
2 
2 
2 
2 
3 
3 
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Program Maintenance Manual 



1. GENERAL INFORMATION 

1.1. Summary. Summarize the general nature of the software to be maintained. 

1.2. Environment. Identify the i)roject sponsor, developer, user and computer cen- 
ter or network where the software is implemented. 

1.3. References. List applicable references, such as: 

a. Project request (authorizations). 

b. Previously published documents on the project. 

c. Documentation concerning related projects. 

d. FIPS publications and other reference documents. 

2. PROGRAM DESCRIPTIONS 

Describe the program and programs in the system/subsystem for the maintenance 
programmer. If a complex system is being described, provide a general description 
of that system identifying each program and its functions. 

2.L Program (Identify) Description. Identify the program by title, tag or label, 
and programming language. 

2.1.1. Problem and Solution Method. Describe the problem to be solved or the 
program function and the solution method used. 

2.1.2. Input. Describe the input to the program and provide a layout. Identify 
the medium used. Include information, such as codes, units of measure- 
mei.'t, format, range of values, or reference a data element directory. 

2.1.3. Processing. Describe processing features and purposes important to the 
maintenance programmer, such as: 

a. Processing logic. 

b. Linkages. 

c. Variables and constants. 

d. FoiTTiulas. 

e. Error handling provisions. 

f. Restrictions and limitations. 

g. Locations, settings, internal switches and flags. 

h. Shared storage. 

2.1.4. Output. Describe the output of the program and provide a layout. Iden- 
tify the medium used. 

2.1.0. Interfaces. Describe the interfaces with other software, such as data 
fomiats, messages, parameters, conversion requirements, interface pro- 
cedures, and media. 

2.1.6. Tables. Identify each table and its items. Describe the location, struc- 
ture, and purpose of each. 
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o 1 7 Run Description. Describe or refcM-once the operating procedures to run 
" tCwam. including loading, oporating. torniinatuig. and erior ban- 
dling. 

2 2 Program (Identify) De.sciplion. Describe the second thr()U8l. nth cc.mputer 
■ ■ program in a manner .'similar to that used in paragraph 2.1. 

3. OrERATINC; ENVIRONMKNT 

1 H-irdwu-e Identify the equipment required for the operation of the system. 
De.saX any uuusiar f^^ used. Relate the hardware to each prog.am. 

Include information such as: 

a Processor and size of internal storage. 

I). Storage online or offline, media, form, and devices. 

c. Input/output devices, online and offline. 

d. Data tran.sniission devices. 

3.2. Support Software. Identify the support software needed for each computcH- 
program. 

■\ o 1 Oner-itine Svstem Identify and describe the operating system includ- 
bg VI. " feSion or release mnnber and any unusual features used. 

Compiler Assembler. Identify and describe the conM\iler or assembler 
iiichiding Vhe version or release number and any .special features used. 

3 •> .S Other Software. Identify and describe any other software used includ- 
ing data management .systems, report generators, etc. 

■> o l)p<;rribe or reference documentation on the data base used In- 

dude ,Kma\ion such as c.des, units of measurement, format, range of values, 
or reference a data element directory. 



MAINTExN'ANCE PROCEDURES 



4.1. I'rogramming Convention.s. Identify and describe the progi-amming conven- 
tions used, 

reference to test data and testing procedures. 
4 3 Error-Correction Procedures. Describe all error conditions, their sources, and 
procedures for their correction. 

of the data base, temporary modifications needed foi leap yeais oi 
changes, etc. 

4 5 Listings and Flowcharts. Reference, append or describe the method for ob- 
t:'!in!ng copies of listings of the programs and flowcharts. 
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3.9 Test Plan 



s 

atioii criteria. 



Contents 



PnRC 



SECTION 1. GEiNEUAL INFORMATIOiN 

2 

1.1. Summary 2 

1.2. Environment and Pretest Background ■■■■■■■ g 



1.3. Roferences 

2 



SECTION 2. PLAN 

2 

2.1. Software Description | 2 

2.2. Milestones 2 

2.3. Testing ( Identify Location) • ' 2 

2.3.1. Schedule 2 

2.3.2. Requirements ' 2 

2.3.3. Testing Materials 2 

2.3.4. Test Training 3 

2.4. Testing (Identify Location) 

3 

SECTION 3, SPECIFICATIONS AND EVALUATION 

3 

.3.1. Specifications 3 

3.L1. Requirements ' 3 

3.1.2. Software Functions * 3 

8.1.3. Test/ Function Relationship.^ 3 

3.1.4. Test Progression 3 

3.2. Methods and Constraints . 3 

3.2.L Methodology ^ 3 

3.2.2. Conditions 3 

3.2.3. Extent ! i^^! !!!!! 3 

3.2.4. Data Recording 3 

3.2.5. Constraints 3 

3.3. Evaluation 3 

3.3.1. Criteria 7......'.... 3 

3.3.2. Data Reduction 

3 

SECTION 4. TEST DESCRIPTIONS 

8 

4.1. Test (Identify) , 3 

4.1.1. Control 4 

4.1.2. Inputs 4 

4.1.3. Outputs 4 

4.1.4. Procedures 4 

4.2, Test (Identify) 
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Test Plan 



GENERAL INFORMATION 

1.1. Summary. Suniniarize the functions of the software and the tests to be per- 
formed. 

1.2. Environment and Pretest Background, Summarize the history of the project. 
Identify the user or^ranization and computer center where the testing will be 
performed. Descriije any prior testing and note results that may affect this 
testing. 

1.3. References. List applicable references, such as: 

a. Project request (authorization). 

1). Previously published documents on the project. 

c. Documentation concerning related projects. 

d. FJPS iniblications and other reference documents. 

PLAN 

2.L Software Description. Provide a chart and briefly describe the inputs, out- 
puts, and functions of the software being tested as a frame of reference for 
the test descriptions. 

2.2. Milestones. List the locations, milestones events, and dates for the testing. 

2.3. Testing (Identify Location). Identify the participating organizations and the 
location where the .software will be tested. 

2.3.1. Schedule. Show the detailed schedule of dates and events for the test- 
ing at this location. Such events may include familiarization, training, 
data, as well as the volume and frequency of the input. 

2.3.2. Requirements. State the resource requirements, including: 

a. Equipment. Show the expected period of use, types, and quantities 
of the equipment needed. 

b. Software. List other software that will be needed to support the 
testing that is not part of the software to be tested. 

c. Personnel. List the numbers and skill types of personnel that are 
expected to be available during the test from both the user and de- 
velopment groups. Include any special requirements such as multi- 
shift operation or key personnel. 

2.3.3. Testing Materials. List the materials needed for the test, such as: 

a. Documentation. 

b. Software to be tested and its medium. 

c. Test inputs and sample outputs. 

d. Test control software and worksheets. 

2.3.4. Test Training. Describe or reference the plan for providing training in 
the use of the software being tested. Specify the types of training, per- 
sonnel to be trained, and the training staff. 
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2.3. 

SPECIFICATIONS AND EVALUATION 
3.1. Specifications. 

3.1.1. Requirements. List the functional requirements established by ear- 
lier documentation. 

n 1 2 Software Functions. List the detailed software functions to be exer- 
cised during the overall test. 

3 1 3 Test /Function Relationships. List the tests to be performed on the soft- 
ware and relate them to the functions in paragraph 3.1.2. 

Q 1 1 Tp<,< Protrression Describe the manner in which progression is made 
Irl oJiftest ranother .so that the entire test cycle .s completed. 

3.2. Methods and Constraints. 

3.2.1. Methodology. Describe the general method or strategy of the testing. 

.3.2.2. Conditions. Specify the type of >nP»t f," b^^f"?^^^?,^ '"^^ " 
data, as well as the volume and frequency of the inpui. 

.3 o 3 Extent Indicate the extent of the testing, such as total or partial. In- 
clude any rationale for partial testing. 

:,2.4. Data Rec-ording. Discuss the method to be used for recording the test 
results and other information about the testing. 

3 2 5. Constraints. Indicate anticipated limitations on the test due to test con- 
ditions. such as interfaces, equipment, personnel, data bases. 

.3.3. Evaluation. 

mum number of allowable interrupts or halts. 
3.3.2. Data Reduction. Describe the techniques to be use^ 

ilSLfi^ettds?irS]o^"c^a ^^^-^t should be 

produced to those that are produced. 

4. TEST DESCRIPTIONS 

4 1 Test (Identify). Describe the test to be performed. 

of results. 
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4.1.2. Inputs. Describe the input data and input comnnands used during the 
test. 

4J,3. Outputs, Describe the output data expected as a result of the test and 
any intermediate messages that may be produced. 

4.1.4. Procedures, Specify the step-by-step procedures to accomplish the test 
Include test setup, initialization, steps, and termination. 

4.2. Test (Identify). Describe the second and subsequent tests in a manner similar 
to that used in paragraph 4,1. 
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The Durnose of the Test Analysis Report is to document the test analysis i/sults and 
fiudi^s; pTent tL den.onstrated capabilities and ^f^^^^-^l^^^^^^'^' ^^'"^'^'^ 
basis f.,; preparing a statement of software readiness for miplementation. 



Contents 

PnKo 
2 

SECTION 1. GENERAL INFORMATION 

2 

1.1. Summary 2 

1.2. Environment 2 

1.3. References 

2 

SECTION 2. TEST RESULTS AND FINDINGS 

2 

2-L Test (Identify) 2 

2.1-1. Dynamic Data Performance * ■ ■ 2 

2-1.2. Static Data Performance * ' 2 

2. N. Test (Identify) 

2 

SP:CTI0N 3. SOFTWARE FUNCTION FINDINGS 

' 2 

3.1. Function (Identify) 2 

3.1.1. Performance 2 

3.1.2. Limits ■ ZZZZl S 

3. N. Function (Identify) 

3 

SECTION 4. ANALYSIS SUMMARY 

3 

4.1. Capabilities ^ 

4.2. Deficiencies 3 

4.3. Recommeiidntions and Estimates 
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Test Analysis Report 



1. GENERAL INFORMATION 

1.1. Summary. Summarize both the general functions of the software tested and 
the test analysis performed. 

1.2. Environment. Identify the software sponsor, developer, user organization, and 
the computer center where the software is to be installed. Assess the manner 
in which the test environment may be different from the operational environ- 
ment and the effects of this difference on the tests. 

1.3. References. List applicable references, such as; 

a. Project request (authorization). 

b. Previously published documents on the project. 

c. Documentation concerning related projects. 

d. FTPS publications and other reference documents. 

2. TEST RESULTS AND FINDINGS 

Identify and present the results and findings of each test separately in paragraphs 
2.1 through 2.N. y B y 

2.1. Test (Identify). 

2.1.1. Dynamic Data Performance. Compare the dynamic data input and out- 
put results, including the output of internally generated data, of this 
test with the dynamic data input and output requirements. State the 
findings. 

2.1.2. Static Data Performance. Compare the static data input and output 
results, including the output of internally generated data, of this test 
with the static data input and output requirements. State the findings. 

2.N. Test (Identify). Present the results and findings of the second and succeeding 
tests in a manner similar to that of paragraph 2.1. 

3. SOFTWARE FUNCTION FINDINGS 

Identify and describe the findings on each function separately in paragraphs 3.1 
through 3.N. 

3.1. Function (Identify). 

3.1.1. Perfcv:. r\ Describe briefly the function. Describe the software ca- 
pabiliu' Vv'ere designed to satisfy this function. State the findings 
as to the demonstrated capabilities from one or more tests. 

3.1.2. Limits. Describe the range of data values tested, including both dy- 
namic and static data. Identify the deficiencies, limitations, and con- 
straints detected in the software during the testing with respect to this 
function. 
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3.N. Function (Identify). Present the findings on the second and succeeding f 
tions in a manner simihu* to that of paragraph 3.1. 

4. AiNALYSIS SUMMARY 



4 3 Recommendations and Estimates. For each deficiency provide any e 
time and effort required for its correction and any recommendations 

a. The urgency of each correction, 
h. Parties responsible for corrections, 
c. How the corrections should be made. 

State the readiness for implementation of the software. 



4.1. 



demonstration of capabilities. 





3 



U.S. GOVERNMENT PRINTING OfflCE : 1976 O-200-393 



55 



53 



